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Purpose 
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¢ The Instrument Kernel serves as a repository for 
instrument-specific geometry information useful 
within the SPICE context. 


— Always included: 


» If an instrument has a field-of-view (FOV), specifications for 
an instrument’s size, shape, and orientation 


— Other possibilities: 
» Timing parameters 
» Optical parameters 
» Detector geometric parameters 
» Optical distortion parameters 


¢ An antenna or solar array or other structure for 
which pointing is important can also use the IK 


¢ Note: instrument mounting alignment data are 
specified in a mission’s Frames Kernel (FK) 
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l-Kernel Structure 
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¢ An |-Kernel is a SPICE text kernel. The format and structure 
of a typical I-Kernel is shown below. 


KPL/IK 
Comments describing the keywords and values 
to follow, as well as any other pertinent 
information. 


\begindata 
Keyword = Value(s) Assignment 
Keyword = Value(s) Assignment 


\begintext 
More descriptive comments. 
\begindata 
Keyword = Value(s) Assignment 


\begintext 


More descriptive comments. 
etc ... 
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l-Kernel Contents (1) 
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¢ The requirements on keywords in an IK are the following: 


— Keywords must begin with INS[#], where [#] is replaced with the NAIF 
instrument ID code (which is a negative number) 


— The total length of the keyword must be less than or equal to 32 characters 
— Keywords are case-sensitive (Keyword != KEYWORD) 


¢ Examples of IK keywords, with descriptions: 
— INS-94031_FOCAL_LENGTH MGS MOC NA focal length 
— INS-41220_ IFOV MEX HRSC SRC pixel angular size 
— INS-41130_. NUMBER_OF_SECTORS MEX ASPERA NPI number of sectors 


¢ In general SPICE does not require any specific keywords to be 
present in an IK 


¢ One exception is a set of keywords defining an instrument’s FOV, if the 
SPICE Toolkit’s GETFVN or GETFOV routine is planned to be used to 
retrieve the FOV attributes 
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l-Kernel Contents (2) 


Navigation and Ancillary Information Facility 


¢ IKs should contain extensive comments regarding: 
— Instrument overview 
— Reference source(s) for the data included in the IK 
— Names/IDs assigned to the instrument and its parts 
— Explanation of each keyword included in the file 
— Description of the FOV and detector layout 


— Where appropriate, descriptions of the algorithms in which parameters 
provided in the IK are used, and even fragments of source code 
implementing these algorithms 


» For example optical distortion models or timing algorithms 


¢ These comments exist primarily to assist users in integrating 
l-Kernel data into their applications 


— One needs to know the keyword name to get its value(s) from the IK data 
— One needs to know what each value means in order to use it properly 
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I-Kernel Interface Routines 
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¢ As with any SPICE kernel, an IK is loaded using FURNSH 


CALL FURNSH ( ’ik file name.ti’ ) { Better yet, use a FURNSH kernel} 


¢ By knowing the name and type (DP, integer, or character) of a 
keyword of interest, the value(s) associated with that keyword can be 
retrieved using G*POOL routines 


CALL GDPOOL ( NAME, START, ROOM, N, VALUES, FOUND ) for DP values 
CALL GIPOOL ( NAME, START, ROOM, N, VALUES, FOUND ) for integer values 
CALL GCPOOL ( NAME, START, ROOM, N, VALUES, FOUND ) for character strings 


¢ When an instrument’s FOV is defined in the IK using a special set of 
keywords discussed later in this tutorial, the FOV shape, reference 
frame, boresight vector, and boundary vectors can be retrieved by 
calling the GETFVN and GETFOV routines 


CALL GETFVN ( INSNAM, ROOM, SHAPE, FRAME, BSIGHT, N, BOUNDS) 


CALL GETFOV ( INSTID, ROOM, SHAPE, FRAME, BSIGHT, N, BOUNDS) 


FORTRAN examples are shown 
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FOV Definition Keywords (1) 
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¢ The following keywords defining FOV attributes for the 


instrument with NAIF ID (#) must be present in the IK if the 
SPICE Toolkit’s GETFNV or GETFOV module will be used 


— Keyword defining shape of the FOV 


INS# FOV_SHAPE = 'CIRCLE' or 'ELLIPSE' or 
"RECTANGLE' or 'POLYGON' 


— Keyword specifying the reference frame in which the boresight vector 
and FOV boundary vectors are specified 


INS# FOV_FRAME = 'frame name' 
— Keyword defining the boresight vector 


INS# BORESIGHT = (xX, Y, Z) 


continued on next page 
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FOV Definition Keywords (2) 
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— Keyword(s) defining FOV boundary vectors, provided in either of 
two ways 


1) By specifying boundary vectors explicitly 


INS# FOV CLASS SPEC 


_FOV_ ¥ = 'CORNERS’ 
INS# FOV_BOUNDARY CORNERS = 


( X(1), ¥(1), 2(1), 
X(n), Y(n), Z2(n) ) 
where the FOV BOUNDARY CORNERS keyword provides an 


array of vectors that poinfto the "corners" of the instrument 
field of view. 


Note: Use of the INS# FOV_CLASS_ SPEC keyword is optional 
when explicit boundary vectors are provided. 


continued on next page 
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FOV Definition Keywords (3) 
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2) By providing half angular extents of the FOV (possible only for circular, 
elliptical or rectangular FOVs) 


INS# FOV CLASS SPEC = 'ANGLES' 

INS# FOV REF VECTOR =( x, 24 
INS# FOV_REF ANGLE = halfanglel 
INS# FOV CROSS ANGLE halfangle2 


"DEGREES' or 
"RADIANS’ or ... 


INS# FOV ANGLE UNITS 


where the FOV_REF_ VECTOR keyword specifies a reference vector that, 
together with the boresight vector, define the plane in which the half 
angle given in the FOV_REF_ ANGLE keyword is measured. The other half 
angle given in the FOV_CROSS_ANGLE keyword is measured in the plane 
normal to this plane and containing the boresight vector. 
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FOV Definition Keywords (4) 
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When explicit boundary vectors are provided, they must be listed 
in either clockwise or counter-clockwise order, not randomly 
Neither the boresight nor reference vector has to be co-aligned 
with one of the FOV frame’s axes 

— But for convenience, each is frequently defined to be along one of the FOV axes 
None of the boresight, corner or reference vector has to be a unit 
vector 

— But these frequently are defined as unit vectors 
When a FOV is specified using the half angular extents method, 
the boresight and reference vectors have to be linearly 
independent but they don’t have to be perpendicular 

— But for convenience the reference vector is usually picked to be normal to the 

boresight vector 

Half angular extents for a rectangular FOV specify the angles 
between the boresight and the FOV sides, i.e. they are for the 
middle of the FOV 


The next several pages show examples of FOV definitions 


Circular Field of View 
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Consider an instrument with a circular field of view. 


X 
Boundary (0,1,4) 

Subtended field of Corner ae 

view angle Vector 

14.03 = arc tan (1/4) oc Z 

a _. 
Boresight 
eal 
. Vector 
(0,0,0) 
Instrument 


focal point 
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Circular FOV Definition 
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The following sets of keywords and values describe this 
circular field of view: 


Specifying boundary vectors explicitly: 


INS-11111 FOV SHAPE = 'CIRCLE' 
INS-11111 FOV FRAME = 'FRAME FOR INS-11111' 
INS-11111 BORESIGHT = (0.0 0.0 1.0) 


INS-11111 FOV_BOUNDARY CORNERS = (0.0 1.0 4.0 ) 


Specifying half angular extents of the FOV: 


INS-11111 FOV_SHAPE = 'CIRCLE' 

INS-11111 FOV FRAME = 'FRAME FOR_INS-11111' 
INS-11111_ BORESIGHT = (0.0 0.0 1.0) 
INS-11111 FOV_CLASS SPEC = 'ANGLES' 

INS-11111 FOV REF VECTOR = (0.0 1.0 0.0 ) 
INS-11111 FOV REF ANGLE = 14.03624347 


INS-11111 FOV ANGLE UNITS = 'DEGREES' 
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Elliptical Field of View 
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Consider an instrument with an elliptical field of view. 


a Boresight 
Boundary Vector 
Corner (0,1,4) 
Subtended field of Vectors 


view angle 
14.03 = arc tan (1/4) 
26.57 = arc tan (2/4) 
on 
(0,0,0) 


Instrument 
focal point 
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Elliptical FOV Definition 
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The following sets of keywords and values describe this 
elliptical field of view: 


Specifying boundary vectors explicitly: 
INS-22222 FOV_ SHAPE = 'ELLIPSE' 
INS-22222 FOV_ FRAME = 'FRAME FOR _INS-22222' 
INS-22222 BORESIGHT 1.0 ) 
INS-22222 FOV BOUNDARY CORNERS = ( 0.0 


I 
~ 
co) 
° 
co) 
oO 


Specifying half angular extents of the FOV: 


INS-22222 FOV SHAPE 'ELLIPSE' 
INS-22222 FOV FRAME 'FRAME FOR _INS-22222' 
INS-22222 BORESIGHT (0.0 0.0 1.0 ) 
INS-22222 FOV_CLASS SPEC 'ANGLES' 

INS-22222 FOV REF VECTOR (0.0 1.0 0.0 ) 
INS-22222 FOV REF ANGLE 14 .03624347 
INS-22222 FOV_CROSS ANGLE 26.56505118 
INS-22222 FOV ANGLE UNITS 'DEGREES ' 
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Rectangular Field of View 
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Consider an instrument with a rectangular field of view. 


Boundary 


Corner (2,1,4) . (-2,1,4) 
Subtended field of Vectors aA -_ 
view angle Y id Z 
14.03 = en (1/4) —" 
26.57 = arc tan (2/4) N 

X ee a Boresight 
—— “aa Vector 
(0,0,0) (2,-1,4) (-2,-1,4) 
Instrument 


focal point 
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Rectangular FOV Definition 
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The following sets of keywords and values describe this 
rectangular field of view: 
Specifying boundary vectors explicitly: 


INS-33333 FOV_SHAPE = ’RECTANGLE' 
INS-33333 FOV FRAME 'FRAME FOR_INS-33333' 


INS-33333 BORESIGHT = (0.0 0.0 1.0 ) 
INS-33333 FOV_ BOUNDARY CORNERS = ( 2.0 1.0 4.0 
-2.0 1.0 4.0 
-2.0 -1.0 4.0 
2.0 -1.0 4.0 ) 
Specifying half angular extents of the FOV: 
INS-33333 FOV_SHAPE = '/RECTANGLE' 


INS-33333 FOV FRAME 
INS-33333 BORESIGHT 
INS-33333 FOV_CLASS SPEC 
INS-33333 FOV REF VECTOR 
INS-33333 FOV REF ANGLE 
INS-33333 FOV CROSS ANGLE 
INS-33333 FOV ANGLE UNITS 


'FRAME FOR_INS-33333' 
(0.0 0.0 1.0) 
'ANGLES ' 

(0.0 1.0 0.0 ) 

14 .03624347 
26.56505118 

'DEGREES ' 
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Consider an instrument with a trapezoidal field of view. 


Boundary 
Corner (1,1,4) , (-1,1,4) 
Vectors -o- , 


i Boresight 
Vector 


(0,0,0) 


Instrument 
focal point 
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Polygonal FOV Definition 
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The following sets of keywords and values describe this 
polygonal field of view: 


Specifying boundary vectors explicitly: 


INS-44444 FOV SHAPE = 'POLYGON' 
INS-44444 FOV FRAME = 'FRAME FOR INS-44444' 
INS-44444 BORESIGHT = (0.0 0.0 1.0) 
INS-44444 FOV BOUNDARY CORNERS = (1.0 1.0 4.0 

-1.0 1.0 4.0 

-2.0 -1.0 4.0 

2.0 -1.0 4.0 ) 


¢ A polygonal FOV cannot be specified using half angular extents. 
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NAIE> IK Utility Programs 
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¢ No IK utility programs are included in the Toolkit 


¢ Two IK utility programs are provided on the NAIF 
website (https://naif.jpl.nasa.gov/naif/utilities.html) 


OPTIKS _ displays field-of-view summary for all FOVs defined in 
a collection of IK files. 


BINGO converts IK files between UNIX and DOS text formats 
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¢ The best way to learn more about IKs Is to 
examine some found in the NAIF Node archives. 
— Start looking here: 
https://naif.jpl.nasa.gov/naif/data_archived.html 


¢ NAIF does not yet have an “I-Kernel Required 
Reading” document 
¢ But information about IKs is available in other 
documents: 
— header of the GETFOV routine 
— Kernel Required Reading 
— OPTIKS User’s Guide 
— Porting_kernels tutorial 
— NAIF IDs Tutorial 
— Frames Required Reading 
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Additional Information on IK 
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¢ The best way to learn more about IKs Is to 
examine some found in the NAIF Node archives. 
— Start looking here: 
https://naif.jpl.nasa.gov/naif/data_archived.html 


¢ NAIF does not yet have an “I-Kernel Required 
Reading” document 
¢ But information about IKs is available in other 
documents: 
— headers of the GETFVN and GETFOV routines 
— Kernel Required Reading 
— OPTIKS User’s Guide 
— Porting_kernels tutorial 
— NAIF IDs Tutorial 
— Frames Required Reading 
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Backup 
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¢ IK file example 


¢ Computing angular extents from corner 
vectors returned by GETFOV 
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Sample IK Data 
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The following LEMMS1 FOV definition was taken 
from the Cassini MIMI IK (cas_mimi_v11.ti): 


Low Energy Magnetospheric Measurements System 1 (LEMMS1) 


Since the MIMI L 


_LEMIMIS] cececcor’s HOW 16 Circular ameél iic’S Cliamecec is 
degrees, looking down the X-axis in the CASSINI MIMI LEMMS1 frame, we 


(Note we are arbitrarily choosing a vector that terminates in the Z=1 
plane.) 


|-- 1.0 -- 


continues 
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Sample IK Data 
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FOV definition from the Cassini MIMI IK (continued): 


The Y component of one 'boundary corner' vector is: 


Y Component = 1.0 * tan ( 7.50 degrees ) 
= 0.131652498 


The boundary corner vector as displayed below is 
normalized to unit length: 
\begindata 


INS-82762 FOV_FRAME 
INS-82762 FOV_SHAPE 
INS-82762 BORESIGHT 


0.0000000000000000 0.0000000000000000 +1.0000000000000000 


) 
INS-82762 FOV BOUNDARY CORNERS = ( 


0.0000000000000000 +0.1305261922200500 +0.9914448613738100 


) 


\begintext 
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Circular FOV Angular Size 
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The angular separation between the boundary 
corner vector and the boresight is the angular size. 


FORTRAN EXAMPLE 


Cc Retrieve FOV parameters. 
CALL GETFOV(-11111, 1, SHAPE, FRAME, BSGHT, N, BNDS) 


Cc Compute the angular size. 
ANGSIZ = VSEP( BSGHT, BNDS(1,1) ) 
C EXAMPLE 


/* Define the string length parameter. */ 
#define STRSIZ 80 


/* Retrieve the field of view parameters. */ 
getfov_c(-11111, 1, STRSIZ, STRSIZ, shape, frame, 
bsght, &n, bnds) ; 


/* Compute the angular separation. */ 
angsiz = vsep_c( bsght, &(bnds[0][0])); 
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Elliptical FOV Angular Size - 1 
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The angular sizes are the angular separations 
between the boresight and the boundary vectors. 


FORTRAN EXAMPLE 


Cc Retrieve the FOV parameters from the kernel pool. 
CALL GETFOV(-22222, 2, SHAPE, FRAME, BSGHT, N, BNDS) 


Cc Compute the angular separations. 

ANG1 = VSEP( BSGHT, BNDS(1,1) ) 

ANG2 = VSEP( BSGHT, BNDS(1,2) ) 
Cc The angle along the semi-major axis is the larger 
Cc of the two separations computed. 

LRGANG = MAX( ANG1, ANG2) 

SMLANG = MIN( ANG1, ANG2) 
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/* 


/* 


/* 


/* 


Elliptical FOV Angular Size - 2 


Navigation and Ancillary Information Facility 


C EXAMPLE 


Define the string length parameter. */ 
#define STRSIZ 80 


Retrieve the FOV parameters from the kernel pool. */ 
getfov_c(-22222, 2, STRSIZ, STRSIZ, shape, frame, 
bsght, &n, bnds) ; 


Compute the angular separations. */ 
angl = vsep_c( bsght, &(bnds[0][0])); 
ang2 = vsep_c( bsght, &(bnds[1][0])); 


The angle along the semi-major axis is the larger of the 
two separations computed. */ 
if ( angl > ang2 ) { 
lrgang = angl; smlang = ang2; } 
else { 
lrgang 


ang2; smlang = angl; } 
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Rectangular FOV Angular Size - 1 
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The angular extents of the FOV are computed by 
calculating the angle between the bisector of 
adjacent unit boundary vectors and the boresight. 


Bisectors 


(0,0,0) 
Subtended field of view 
Instrument angles 
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Rectangular FOV Angular Size - 2 
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FORTRAN EXAMPLE 


Retrieve FOV parameters from the kernel pool. 
CALL GETFOV (-33333, 4, SHAPE, FRAME, BSGHT, N, BNDS) 


Normalize the 3 boundary vectors 

CALL UNORM(BNDS(1,1), UNTBND(1,1), MAG) 
CALL UNORM(BNDS (1,2), UNTBND(1,2), MAG) 
CALL UNORM(BNDS (1,3), UNTBND(1,3), MAG) 


Compute the averages. 
CALL VADD (UNTBND(1,1), UNTBND(1,2), VEC1) 
CALL VSCL(0.5, VEC1, VEC1) 


CALL VADD (UNTBND (1,2), UNTBND(1,3), VEC2) 
CALL VSCL(0.5, VEC2, VEC2) 


Compute the angular separations 
ANG1 = VSEP( BSGHT, VEC1 ) 
ANG2 = VSEP( BSGHT, VEC2 ) 


Separate the larger and smaller angles. 
LRGANG = MAX( ANG1, ANG2) 
SMLANG = MIN( ANG1, ANG2) 
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/* 


/* 


/* 


/* 


/* 


/* 


Rectangular FOV Angular Size - 3 
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C EXAMPLE 


Define the string length parameter. */ 
#define STRSIZ 80 


Retrieve the FOV parameters from the kernel pool. */ 
getfov_c(-33333, 4, STRSIZ, STRSIZ, shape, frame, 
bsght, &n, bnds) ; 


Normalize the 3 boundary vectors. */ 

unorm_c(&(bnds[0][0]), &(untbnd[0][0]), &mag) ; 
unorm_c(&(bnds[1][0]), &(untbnd[1][0]), &mag) ; 
unorm_c(&(bnds[2][0]), &(untbnd[2][0]), &mag) ; 


Compute the averages */ 
vadd_c(&(untbnd[0][0]), &(untbnd[1][0]), vecl) ; 
vscl_c(0.5, vecl, vecl) ; 
vadd_c(&(untbnd[1][0]), &(untbnd[2][0]), vec2) ; 
vscl_c(0.5, vec2, vec2) ; 


Compute the angular separations. */ 
angl = vsep_c( bsght, vecl) ; 
ang2 = vsep_c( bsght, vec2) ; 


Separate the larger and smaller angles. */ 
if ( angl > ang2 ) { 
lrgang = angl; smlang 
else { 
lrgang = ang2; smlang = angl; } 


ang2; } 
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